API Design Pattern of the Week 20: Retrieval Operation

A pattern from the book “Patterns of API Design: Simplifying Integration with Loosely Coupled Message Exchanges”

Published in

ZIO’s Blog

4 min readDec 6, 2023

a.k.a. Read-Only Operation

The first 14 patterns in this “API Design Pattern of the Week” series came as LinkedIn articles; patterns 15 to 19 as Medium stories. All series members are listed and linked in the series index and overview.

Note: This online excerpt of the pattern predates its final version in the book.

Context

API clients(s) demand read only access to large amounts of structured, possibly aggregated data. This data can be expected to be structured differently than in the underlying domain model; for instance, it might pertain to a particular time interval or domain element (like a product category or customer profile group).

Problem

How can information available from a remote party (the API provider, that is) be retrieved to satisfy an information need of an end user or to allow further client-side processing?

Related design issues are:

How can data model differences be overcome and data be aggregated and combined with information from other sources?
How can clients influence the scope and the selection criteria for the retrieval results?
How can the time frame for reports be specified?

Forces

The following forces arise when exposing data-centric API operations:

Veracity, variety, velocity, volume, four of the five Vs in big data.
Workload management
Networking efficiency vs. data parsimony (message sizes)

These pattern forces are explained in depth in our book.

Solution Sketch

Add a read-only operation ro: (in,S) -> out to an API endpoint, which often is an Information Holder Resource, to request a result report that contains a machine-readable representation of the requested information. Add search, filter, and formatting capabilities to the operation signature.

A simple graphical sketch (from pre-book times) that visualizes the read-only nature of this operation type is:

Examples

In an online shopping example, an analytic Retrieval Operation “show all orders customer ABC has placed in the last 12 months”.

In the Lakeside Mutual example, we can define two operations to find customers as illustrated in Figure 2. CRM stands for Customer Relationship Management; the allData parameter allows to return either an Embedded Entity or a Linked Information Holder.

A code-level example is:

curl http://localhost:8080/claims?limit=10\&offset=0 

@GET public ClaimsDTO listClaims( 
  @DefaultValue("3") 
  @QueryParam("limit") Integer limit, 
  @DefaultValue("0") 
  @QueryParam("offset") Integer offset, 
  @QueryParam("orderBy") String orderBy 
) { 
  List<ClaimDTO> result = [...] 
    return new ClaimsDTO(limit, offset, claims.getSize(), orderBy, result); 
}

Implementation Hints

The EuroPLoP 2020 version of the pattern provides implementation hints (article PDF).

Consequences

Forces resolution and other consequences are discussed in the book.

Known Uses

See pattern coverage on our website.

Related Patterns

The endpoint pattern Processing Resource and all types of Information Holder Resources may expose Retrieval Operations. The Pagination pattern is often applied in Retrieval Operations.

There are three sibling patterns State Transition Operation, State Creation Operation, and Computation Function. They capture other read/write characteristics:

Patterns for API Design: Four Types of Operations: read, write, read-write, stateless

A State Creation Operation pushes data from the client to the API provider, whereas a Retrieval Operation pulls data; both Computation Function and State Transition Operation can support both unidirectional data flows and bidirectional ones.

Variants

Several variants of this pattern exist, for instance Status Check (a.k.a. Progress Inquiry/Polling) and Time-Bound Report.

Other Sources

The is a large body of literature on database design and information integration, including data warehouses (Kimball and Ross (2002)).

Chapter 8 in the RESTful Web Services Cookbook (Allamaraju (2010)) discusses queries (in the context of HTTP APIs).

“Implementing Domain-Driven Design” (Vernon (2013)) talks about Query Models in Chapter 4 (in the section on CQRS). Endpoints that only expose Retrieval Operations form the Query Model in CQRS.

References

Allamaraju, Subbu. 2010. RESTful Web Services Cookbook. O’Reilly.

Kimball, Ralph, and Margy Ross. 2002. The Data Warehouse Toolkit: The Complete Guide to Dimensional Modeling. 2nd ed. Wiley.

Vernon, Vaughn. 2013. Implementing Domain-Driven Design. Addison-Wesley.

Zimmermann, Olaf and Stocker, Mirko and Lübke, Daniel and Zdun, Uwe and Pautasso, Cesare. 2022. Patterns for API Design: Simplifying Integration with Loosely Coupled Message Exchanges, Vaughn Vernon Signature Series, Addison-Wesley Professional.